QuickTime 4 Reference

Displaying the Standard Parameters Dialog Box

Use the QTCreateStandardParameterDialog function to display the standard parameters dialog box. This allows the user to choose an effect, adjust the settings for that effect, and see a preview of the effect with the selected settings.

Use of this function is described below. For additional details, see the function definition "QTCreateStandardParameterDialog" .

When you call QTCreateStandardParameterDialog , QuickTime creates a standard parameters dialog box. The contents of the dialog box vary, depending on the list of effects you pass to the function and the set of parameters for the currently chosen effect.

Calling QTCreateStandardParameterDialog does not immediately display the dialog box; it only prepares it for display. The dialog box is shown the first time you call QTIsStandardParameterDialogEvent to process events for the dialog box. Event handling is described in "Processing Standard Parameter Dialog Box Events" .

The standard parameters dialog box for Apple's film noise effect is shown in Figure 9 .

Figure 9 The standard parameters dialog box showing Apple's film noise effect

Notice that the dialog box has three main sections. In the upper-left corner is a scrolling list of all the effect components. To the right of this are the parameters of the chosen effect. As you select different items in the list of effects, the parameters change appropriately. There is also an effect preview area below the list of effects. This shows a preview of the chosen effect and parameter settings.

The user interface for setting the value of a parameter may be a slider, as shown in the example above, a set of radio buttons, an editable text field, or any of several other interfaces specified in the parameter description's kParameterDataBehavior field.

For parameters that are always tweens, the user is presented with a starting and ending value. For parameters that can be tweened optionally, the dialog box presents the user with a single value by default. In order to set such a parameter to a tweened value, the user must hold down the Option key when selecting an effect.

Note that your application does not need to know what effects are available, what their parameters are, or what kind of control to use when setting a parameter. All these details are handled by the standard dialog box function.

The function call to create and display this dialog box is



 
QTCreateStandardParameterDialog(theEffectList,

                        theEffectParameters,

                        0,

                        &createdDialogID);

The variable theEffectList holds the list of effects returned by QTGetEffectsList . You can also pass nil for this value, in which case QTCreateStandardParameterDialog calls QTGetEffectsList to generate the list of all the currently installed effects, then shows these effects. On input, theEffectParameters contains a QTAtomContainer that holds the initial values of the effect's parameters. In most cases, you should pass an empty QTAtomContainer as this argument, in which case the default values of each effect are shown.

The third argument specifies how to deal with parameters that can be tweened. Passing in a 0 selects the default behavior, which allows the user to set a starting and ending value for parameters that must be tweens, but only allows the user to set a single value for parameters that are optionally tweens.

When the user selects the dialog box's OK button, the chosen effect's parameter values are returned in theEffectParameters . The parameter values are returned in a QTAtomContainer that you can use as an effect description. You will need to add kEffectSourceName atoms for effects that use one or more sources.

The createdDialog argument returns an ID number that is passed to the other functions that deal with the standard parameters dialog box. This is explained in detail in the next section.